home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / programming / gui / bgui11b.lha / docs / groupclass.doc < prev    next >
Encoding:
Text File  |  1995-01-03  |  12.7 KB  |  331 lines
  1.  
  2.            $RCSfile: groupclass.doc,v $
  3.         Description: Groupclass documentation.
  4.           Copyright: (C) Copyright 1994 Jaba Development.
  5.                      (C) Copyright 1994 Jan van den Baard.
  6.                      All Rights Reserved.
  7.  
  8.             $Author: jaba $
  9.           $Revision: 1.6 $
  10.               $Date: 1994/11/09 20:23:01 $
  11. ------------------------------------------------------------------------------
  12.  
  13. TABLE OF CONTENTS
  14.  
  15. groupclass/--background--
  16. groupclass/Methods
  17. groupclass/Attributes
  18.  
  19. groupclass/--background--                            groupclass/--background--
  20.  
  21.     NAME
  22.         Class:          groupclass
  23.         Superclass:     baseclass
  24.         Include File:   <libraries/bgui.h>
  25.  
  26.     FUNCTION
  27.         To layout it's members in a specific area.   A groupclass  object may
  28.         have any number of members which are layouted accoording  to a set of
  29.         layout attributes.
  30.  
  31.         The number of members a group can have is only limited by  the amount
  32.         of available memory. This will allow for simple and extremely complex
  33.         layout's.
  34.  
  35. groupclass/Methods                                         groupclass/Methods
  36.  
  37.     NEW METHODS
  38.         GRM_ADDMEMBER -- This  method  can  be  used  to  add  a member to an
  39.                 existing group. This method uses the following custom message
  40.                 structure:
  41.  
  42.                 struct grmAddMember {
  43.                         ULONG           MethodID;    /* GRM_ADDMEMBER */
  44.                         Object         *grma_Member; /* Object to add. */
  45.                         ULONG           grma_Attr;
  46.                 };
  47.  
  48.                 grma_Attr -- This is an array of attributes which control the
  49.                         way the object is layouted.  The following attributes
  50.                         are possible:
  51.  
  52.                         LGO_FixWidth -- ti_Data contains the  width at  which
  53.                                 the object is fixed.
  54.  
  55.                         LGO_FixHeight -- ti_Data contains the height at which
  56.                                 the object is fixed.
  57.  
  58.                         LGO_Weight -- Scaling objects  is weight  controlled.
  59.                                 the default weight  an  object  get's  is 50.
  60.                                 This attribute  can  be  used to  change that
  61.                                 setting.
  62.  
  63.                         LGO_FixMinWidth -- The  object   is  fixed   at  it's
  64.                                 minimum width.
  65.  
  66.                         LGO_FixMinHeight -- The  object  is  fixed   at  it's
  67.                                 minimum height.
  68.  
  69.                         LGO_Align -- Normally  only  objects  in  a  vertical
  70.                                 group are aligned when they  have a  label on
  71.                                 the left side  of  their  hitbox.  When  this
  72.                                 attribute is TRUE the object will get aligned
  73.                                 wherever the label is placed.
  74.  
  75.                         LGO_NoAlign ** V38 ** -- Normally  all  objects  in a
  76.                                 vertical group with a label  on  the  left of
  77.                                 the hitbox are all aligned. This tag prevents
  78.                                 this.
  79.  
  80.                 Example:
  81.                         Object          *group, *cycle;
  82.  
  83.                         DoMethod( group, GRM_ADDMEMBER, cycle,
  84.                                   LGO_FixMinHeight, TRUE,
  85.                                   LGO_Weight,       DEFAULT_WEIGHT,
  86.                                   TAG_END );
  87.  
  88.                 This adds a cycle object to a group fixing the height to it's
  89.                 minimum size and the weight to 50.
  90.  
  91.                 Please note that the weight of an object  affects to  with of
  92.                 the object in a horizontal group and the height of the object
  93.                 in a vertical group.
  94.  
  95.                 This method may only be used when the  group  is _not_ active
  96.                 (I.E. displayed in a window).
  97.  
  98.                 Returns TRUE uppon success, FALSE uppon failure.
  99.  
  100.                 If this method was successfull you do not need to dispose  of
  101.                 the added member anymore. This will be disposed of as soon as
  102.                 the group to which the member was added is disposed of.
  103.  
  104.         GRM_REMMEMBER -- With  this method you  can remove  an object  from a
  105.                 group again. This method  uses the  following  custom message
  106.                 structure:
  107.  
  108.                 struct grmRemMeber {
  109.                         ULONG           MethodID;    /* GRM_REMMEMBER */
  110.                         Object         *grmr_Member; /* Object to remove. */
  111.                 };
  112.  
  113.                 This method may only be used when the  group  is _not_ active
  114.                 (I.E. displayed in a window).
  115.  
  116.                 Return code not defined.
  117.  
  118.                 You are responsible for disposing of the removed object.
  119.  
  120.         GRM_DIMENSIONS -- This method is sent to all members to inquire about
  121.                 their minimum sizes. Please refer to the  "methods.doc"  file
  122.                 for more information on this method.
  123.  
  124.         GRM_ADDSPACEMEMBER -- This method can be used to  add a  special kind
  125.                 of  object  to  the  group.   The  member  will  be  a weight
  126.                 controlled  spacing  in  the  group.   This  method  uses the
  127.                 following custom message structure:
  128.  
  129.                 struct grmAddSpaceMember {
  130.                         ULONG           MethodID;   /* GRM_ADDSPACEMEMBER */
  131.                         ULONG           grms_Weight;
  132.                 };
  133.  
  134.                 grms_Weight -- This  field  must  contain  the  weight of the
  135.                         spacing object.   Please refer  to the  GRM_ADDMEMBER
  136.                         section for more information about weights.
  137.  
  138.                 This method may only be used when the  group  is _not_ active
  139.                 (I.E. displayed in a window).
  140.  
  141.                 Returns TRUE uppon success, FALSE uppon failure.
  142.  
  143.         GRM_INSERTMEMBER --  This   method   is   basically   the   same   as
  144.                 GRM_ADDMEMBER with the exception that you can determine where
  145.                 the object is added.  This  method  uses the following custom
  146.                 message structure:
  147.  
  148.                 struct grmInsertMember {
  149.                         ULONG           MethodID;    /* GRM_INSERTMEMBER */
  150.                         Object         *grmi_Member; /* Object to add. */
  151.                         Object         *grmi_Pred;
  152.                         ULONG           grmi_Attr;
  153.                 };
  154.  
  155.                 grmi_Pred -- This must point to  the object  after  which the
  156.                         new member is inserted.  You may set this to  NULL in
  157.                         which case the new member is inserted at the start of
  158.                         the list.
  159.  
  160.                 grmi_Attr -- This is an array of attributes which control the
  161.                         way the object is layouted.   The  attributes allowed
  162.                         here are exactly the same as the  attributes  you can
  163.                         use with the GRM_ADDMEMBER method.
  164.  
  165.                 Example:
  166.                         Object          *group, *cycle, *button;
  167.  
  168.                         DoMethod( group, GRM_INSERTMEMBER, cycle, button,
  169.                                   LGO_FixMinHeight, TRUE,
  170.                                   LGO_Weight,       DEFAULT_WEIGHT,
  171.                                   TAG_END );
  172.  
  173.                 This adds a cycle object to a group fixing the height to it's
  174.                 minimum  size  and  the weight to 50.  The  cycle  object  is
  175.                 inserted after the button object.
  176.  
  177.                 Please note that the weight of an object  affects to  with of
  178.                 the object in a horizontal group and the height of the object
  179.                 in a vertical group.
  180.  
  181.                 This method may only be used when the  group  is _not_ active
  182.                 (I.E. displayed in a window).
  183.  
  184.                 Returns TRUE uppon success, FALSE uppon failure.
  185.  
  186.                 If this method was successfull you do not need to dispose  of
  187.                 the added member anymore. This will be disposed of as soon as
  188.                 the group to which the member was added is disposed of.
  189.  
  190.     CHANGED METHODS
  191.         OM_DISPOSE -- When this  method is called it will  also dispose of all
  192.                 objects that are added to the group.
  193.  
  194. groupclass/Attributes                                    groupclass/Attributes
  195.  
  196.     NAME
  197.         GROUP_Style -- ( ULONG )
  198.  
  199.     FUNCTION
  200.         Set  the  style  of  the  group  to  create.  The following styles are
  201.         possible:
  202.  
  203.         GRSTYLE_HORIZONTAL -- A horizontal group is created.
  204.  
  205.         GRSTYLE_VERTICAL -- A vertical group is created.
  206.  
  207.         Default is GRSTYLE_HORIZONTAL. Applicability is (I).
  208.  
  209.     NAME
  210.         GROUP_Spacing -- ( ULONG )
  211.  
  212.     FUNCTION
  213.         Set  the  number of pixels the group uses as a space between the group
  214.         members.
  215.  
  216.         Default is 0. Applicability is (I).
  217.  
  218.     NAME
  219.         GROUP_HorizOffset,         GROUP_VertOffset,         GROUP_LeftOffset,
  220.         GROUP_RightOffset, GROUP_TopOffset, GROUP_BottomOffset -- ( ULONG )
  221.  
  222.     FUNCTION
  223.         Set the offset in pixels from the group borders at which the layouting
  224.         is started. Please note that frames are not taken into consideration.
  225.  
  226.         Default is 0. Applicability is (I).
  227.  
  228.     NAME
  229.         GROUP_Member -- ( Object * )
  230.  
  231.     FUNCTION
  232.         To add a member to a group at initialization time.  This tag is read a
  233.         little different than the other tags.  Following  the object a  set of
  234.         layout attributes can be passed. Example:
  235.  
  236.         UBYTE           *labels[] = { "LAB1", "LAB2", NULL };
  237.         Object          *group, *cycle;
  238.  
  239.         /* With macros */
  240.         group = HGroupObject,
  241.                 StartMember,
  242.                         cycle = Cycle( "Cycle", labels, 0, 0 ),
  243.                         FixMinHeight, Weight( DEFAULT_WEIGHT ),
  244.                 EndMember,
  245.         EndObject;
  246.  
  247.         /* Without macros */
  248.         group = BGUI_NewObject( BGUI_GROUP_GADGET,
  249.                 GROUP_Member,
  250.                         cycle = BGUI_NewObject( BGUI_CYCLE_GADGET,
  251.                                 LAB_Label,      "Cycle",
  252.                                 CYC_Labels,     labels,
  253.                                 CYC_Active,     0,
  254.                                 GA_ID,          0,
  255.                                 TAG_END ), LGO_FixMinHeight, TRUE,
  256.                                            LGO_Weight, DEFAULT_WEIGHT,
  257.                                            TAG_END, 0,
  258.                 TAG_END );
  259.  
  260.         As you can see the layout attributes follow the object  pointer in the
  261.         ti_Data field directly. Therefore it is also important that the layout
  262.         attributes are terminated  with a  TAG_END, 0  rather  then  a  single
  263.         TAG_END. The macros will automatically do this for you.
  264.  
  265.         If by any chance the object you add is NULL. The creation of the group
  266.         will fail. All objects that where successfully added to the  group are
  267.         disposed of in this case.
  268.  
  269.         Default is NULL. Applicability is (I).
  270.  
  271.     SEE ALSO
  272.         Methods/GRM_ADDMEMBER
  273.  
  274.     NAME
  275.         GROUP_SpaceObject -- ( ULONG )
  276.  
  277.     FUNCTION
  278.         To add a weight controlled spacing member at create time.  The data of
  279.         this tag should contain the weight of the spacing.
  280.  
  281.         Default is 0. Applicability is (I).
  282.  
  283.     NAME
  284.         GROUP_BackFill -- ( ULONG )
  285.  
  286.     FUNCTION
  287.         To provide a backfill possibility the same as the frameclass supplies.
  288.         The  data  passed  with  this  tag  should  be the same as defined and
  289.         documented   for   the   FRM_BackFill   attribute  of  the  frameclass
  290.         documentation. Please note that this tag  is overided  when  the group
  291.         has a frame attached to it.
  292.  
  293.         Default is 0. Applicability is (I).
  294.  
  295.     SEE ALSO
  296.         frameclass.doc/FRM_BackFill
  297.  
  298.     NAME
  299.         GROUP_EqualWidth -- ( BOOL )
  300.  
  301.     FUNCTION
  302.         To force all members of the group to get the same minimum width.  This
  303.         makes it easy to create a row of objects which  all are  equally wide.
  304.  
  305.         Default is FALSE. Applicability is (I).
  306.  
  307.     SEE ALSO
  308.         GROUP_EqualHeight
  309.  
  310.     NAME
  311.         GROUP_EqualHeight -- ( BOOL )
  312.  
  313.     FUNCTION
  314.         To force all members of the group to get the same minimum height. This
  315.         makes it easy to create a row of objects which  all are  equally high.
  316.  
  317.         Default is FALSE. Applicability is (I).
  318.  
  319.     SEE ALSO
  320.         GROUP_EqualWidth
  321.  
  322.     NAME
  323.         GROUP_Inverted -- ( BOOL )
  324.  
  325.     FUNCTION
  326.         To force the members added at create time  to be  AddHead()'ed  to the
  327.         member  list  instead  of  AddTail()'ed.   This  is  necessary for the
  328.         assembly macros of the BGUI package.
  329.  
  330.         Default is FALSE. Applicability is (I).
  331.